Inside Macintosh: QuickTime Components
This section describes the functions that your application may supply to sequence grabber components.
Your grab function is used by the sequence grabber component to begin the capture of a frame of video data. Your grab-complete function allows the sequence grabber component to determine whether the current frame-capture operation is complete.
Your display function enables the sequence grabber component to move a captured video image in an offscreen buffer into the destination buffer for the video channel.
The sequence grabber component uses your compress function to commence the compression of a captured video image. Your compress-complete function helps the sequence grabber component to find out if the current frame-compression operation is finished.
Your add-frame function lets the sequence grabber component add a frame to a movie.
The sequence grabber component uses your transfer-frame function to move a video frame from the capture buffer into the channel's filter buffer.
You may provide two functions for use with compressed-source devices. Your grab-compress-complete function determines when the current capture and compress operation is complete. Your display-compress function decompresses and displays a frame.
The sequence grabber calls your data function whenever any of the grabber's channels write data to the movie file.
If you call the SGSettingsDialog function, described on SGSettingsDialog , you must supply a modal-dialog filter function. The interface that your function must provide is discussed on MyModalFilter .
The sequence grabber component calls your grab function in order to start capturing a frame of video data.
Your grab function must present the following interface:
pascal ComponentResult MyGrabFunction (SGChannel c,
short bufferNum,
long refCon);
Your grab function can use the sequence grabber component's SGGrabFrame function to support the default behavior. SGGrabFrame is described on SGGrabFrame .
The sequence grabber component calls your grab-complete function in order to determine whether the current frame-capture operation is complete. Once a frame has been completely captured, you can modify its contents to suit your needs. For example, you can overlay text onto the video image.
Your function must present the following interface:
pascal ComponentResult MyGrabCompleteFunction (SGChannel c,
short bufferNum,
Boolean *done,
long refCon);
Your grab-complete function can use the sequence grabber component's SGGrabFrameComplete function to support the default behavior. SGGrabFrameComplete is described on SGGrabFrameComplete .
See Listing 6 for a sample grab-complete function. This function draws the letters "QT" over each video frame in the sequence.
The sequence grabber component calls your display function in order to transfer a captured video image in an offscreen buffer into the destination buffer for the video channel.
Your display function must support the following interface:
pascal ComponentResult MyDisplayFunction (SGChannel c,
short bufferNum,
MatrixRecord *mp,
RgnHandle clipRgn,
long refCon);
Your application sets the destination buffer by calling the SGSetChannelBounds function, which is described on SGSetChannelBounds .
Your display function can use the sequence grabber component's SGDisplayFrame function to support the default behavior. SGDisplayFrame is described on SGDisplayFrame .
The sequence grabber component calls your compress function in order to start compressing the captured video image.
Your compress function must support the following interface:
pascal ComponentResult MyCompressFunction (SGChannel c,
short bufferNum,
long refCon);
Your compress function can use the sequence grabber component's SGCompressFrame function to support the default behavior. SGCompressFrame is described on SGCompressFrame . This function uses the Image Compression Manager to compress the video image. For more on the Image Compression Manager, see Inside Macintosh: QuickTime .
The sequence grabber component calls your compress-complete function in order to determine whether the current frame-compression operation is complete.
Your compress-complete function must support the following interface:
pascal ComponentResult MyCompressCompleteFunction (SGChannel c,
short bufferNum,
Boolean *done,
SGCompressInfo *ci,
long refCon);
Your compress-complete function can use the sequence grabber component's SGCompressFrameComplete function to support the default behavior. SGCompressFrameComplete is described on SGCompressFrameComplete .
The sequence grabber component calls your add-frame function in order to add a frame to a movie. Your add-frame function must support the following interface:
pascal ComponentResult MyAddFrameFunction (SGChannel c,
short bufferNum,
TimeValue atTime,
TimeScale scale,
SGCompressInfo *ci,
long refCon);
You can use your add-frame function to modify the contents of the frame before it is added to the movie. This can be useful if you want to place frame numbers onto frames you are recording.
Your add-frame function can use the sequence grabber component's SGAddFrame function to support the default behavior. SGAddFrame is described on SGAddFrame .
The sequence grabber component calls your transfer-frame function in order to move a video frame from the capture buffer into the channel's filter buffer.
Your transfer-frame function must support the following interface:
pascal ComponentResult MyTransferFrameFunction (SGChannel c,
short bufferNum,
MatrixRecord *mp,
RgnHandle clipRgn,
long refCon);
The sequence grabber component calls this function only when you are filtering the video data. By filtering the video data through a filter buffer, you can eliminate some visual artifacts that result from noisy input video sources. Your application sets a filter buffer by calling the SGSetCompressBuffer function, which is described on SGSetCompressBuffer .
If you are using a grab-complete function to determine when frames have been grabbed, you should also implement a grab-compress-complete function (described in the next section). Otherwise, the channel will decompress the specified image before calling your grab-complete function, which will result in significantly lower performance. For details on grab-complete functions, see MyGrabCompleteFunction .
Your transfer-frame function can use the sequence grabber component's SGTransferFrameForCompress function to support the default behavior-- SGTransferFrameForCompress is described on SGTransferFrameForCompress .
The sequence grabber calls your grab-compress-complete function when it is working with a video digitizer that supports compressed source data. Your grab-compress-complete function is responsible for determining whether the current compressed frame has been completely captured and compressed, essentially combining your grab-complete, compress, and compress-complete functions into one function.
Your function must support the following interface:
pascal ComponentResult MyGrabCompressCompleteFunction
(SGChannel c,
Boolean *done,
SGCompressInfo *ci,
TimeRecord *tr,
long refCon);
Your grab-compress-complete function may use the sequence grabber's SGGrabCompressComplete function to support the default behavior. SGGrabCompressComplete is discussed beginning on SGGrabCompressComplete .
The sequence grabber calls your display-compress function when it is working with a video digitizer component that supports compressed source data. Your display-compress function is responsible for decompressing and displaying a compressed image.
pascal ComponentResult MyDisplayCompressFunction (SGChannel c,
Ptr dataPtr,
ImageDescriptionHandle desc,
MatrixRecord *mp,
RgnHandle clipRgn,
long refCon);
Your display-compress function may use the sequence grabber's SGDisplayCompress function to support the default behavior. SGDisplayCompress is discussed beginning on SGDisplayCompress .
The sequence grabber calls your data function whenever any of the grabber's channels write digitized data to the destination movie file. You assign a data function to the sequence grabber by calling the SGSetDataProc function, which is discussed on SGSetDataProc .
Your data function must support the following interface:
pascal OSErr MyDataFunction (SGChannel c, Ptr p, long len,
long *offset, long chRefCon,
TimeValue time, short writeType,
long refCon);
The sequence grabber calls your data function whenever any channel component writes data to the destination movie. You may use your data function to store the digitized data in some format other than a QuickTime movie.
You can instruct the sequence grabber not to write its data to a QuickTime movie by calling the SGSetDataOutput function and setting the seqGrabDontMakeMovie flag to 1. This can save processing time in cases where you do not want to create or update a movie. SGSetDataOutput is discussed on SGSetDataOutput .
The SGSettingsDialog function causes the sequence grabber to present its settings dialog box to the user. This is a movable modal dialog box, so you must provide a filter function to handle update events in your window. You specify your filter function with the proc parameter.
A modal-dialog filter function whose address is passed to SGSettingsDialog should support the following interface:
pascal Boolean MyModalFilter (DialogPtr theDialog,
EventRecord *theEvent,
short *itemHit, long refCon);